Skip to content

🐛 End a switch mutation's retry wait when its call is cancelled - #260

Merged
mbret merged 4 commits into
mainfrom
claude/awesome-bell-2a040j
Nov 10, 2026
Merged

mbret merged 4 commits into
mainfrom
claude/awesome-bell-2a040j

Conversation

@mbret

@mbret mbret commented Nov 10, 2026

Copy link
Copy Markdown
Owner

Why

With retry set, a useSwitchMutation$ call that fails waits before its next attempt: 1 s, then 2 s, up to 30 s by default. If a newer call cancels it during that wait, it stays pending until the wait ends. Meanwhile isMutating() counts it, a call in the same scope waits for it, and its onError can run after the newer call has succeeded. TanStack Query waits with a timer that nothing outside it can stop.

  • Change: TanStack Query gets a retryDelay of 0. A failed attempt waits the delay itself before it hands its error over, and a cancel ends that wait at once.

What's new

Other changes

  • ♻️ utils/retry.ts holds shouldRetry and the default backoff, and useSubscribeEffect uses the same delay lookup
  • ♻️ createSwitchOverrides also builds mutationFn, so every option the hook passes over the caller's comes from one place
  • 📝 The docs page gets a Retries section with what differs from TanStack Query
  • ✅ Tests on fake timers for the cancel, the delay sources, an offline device, a hidden page, a call TanStack Query holds, a synchronous throw, and retry or retryDelay changed during a call

Details

Why the wait is at the end of the failed attempt

After its own wait, TanStack Query checks that the device is online and the page visible, and holds the retry if not. The hook waits before TanStack Query sees the failure, so TanStack Query runs that check in its usual place. A first version waited at the start of the next attempt instead: a device that went offline during the wait then spent the retry offline, and the mutation failed where TanStack Query would have held it. A test now covers that case.

What differs from TanStack Query

The docs page lists these:

  • failureCount and failureReason change when the wait ends, not when the attempt fails. A call cancelled during the wait never records that failure.
  • A retry function runs twice for each failure: once in the hook, to know whether to wait, and once in TanStack Query.
  • A change to retry or retryDelay applies to the calls already running. TanStack Query keeps the starting values, while each attempt runs the latest render's mutationFn. So the hook and TanStack Query both read the latest values, or they would disagree on whether to retry.
  • A call that TanStack Query holds, such as while offline, still fails only when TanStack Query resumes it, as on main.

Tests seen to fail

  • On main, the cancel test fails: the cancelled call has no error yet.
  • On the first version, the offline and hidden-page tests fail.
  • Before the review fixes, a synchronous throw retried with no delay, and a retry changed from true to false made 1011 attempts with no delay. A test now covers each case.

Commits

The branch has one fix commit and three refactor commits from the review. The release notes show one entry for #252.

🔍 Self-reviewed with selfcorrect-review
🤖 Made within harness coverage


Generated by Claude Code

…celled

With `retry` set, TanStack Query waits between two attempts with a timer
that nothing outside its retryer can stop. A useSwitchMutation$ call
cancelled during that wait stayed pending until the wait ended, up to
30 s with the default delay. Meanwhile `isMutating()` counted it, a call
in the same `scope` waited for it, and its `onError` could run after the
next call had succeeded.

TanStack Query now gets a `retryDelay` of 0, and each retry attempt
first waits the delay itself, raced with the call's abort signal. A call
cancelled during the wait fails at once with SwitchMutationCancelError.
The delay comes from the caller's `retryDelay`, the client's default, or
TanStack Query's default, and receives the failure count and the error
that TanStack Query records in the call's mutation before it retries. So
`failureCount`, `failureReason` and the pause while offline still work.

`mutationFn` joins the options that createSwitchOverrides builds, and the
docs page covers retries.

Closes #252

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BvSDyJABLGit75HAjpnsqm
The previous commit waited `retryDelay` at the start of the next attempt.
TanStack Query checks that the device is online and the page visible
after its own wait, and with a wait of 0 it checked before the hook's
wait instead. A device that went offline during the wait spent the retry
offline, and the mutation failed where TanStack Query would have held it
until the device was back online. A call that failed while offline also
waited the full delay again after it came back.

The failed attempt now waits `retryDelay` before it hands its error to
TanStack Query, raced with the call's abort signal. TanStack Query then
runs its own checks in its own order. `failureCount` and `failureReason`
change when the wait ends, and a `retry` function runs twice for each
failure: the docs page says so. The failure count comes from
`failureCount`, so a source that errors with `null` still waits.

- The docs and the JSDoc say that a call TanStack Query holds, such as
  while offline, fails when it resumes, not at once.
- `utils/retry.ts` holds `shouldRetry`, `defaultRetryDelay` and
  `getRetryDelay`, and useSubscribeEffect uses them instead of its own
  copy of the backoff.
- Tests run on fake timers, and cover a device going offline or a page
  hidden during the wait, and a cancel while TanStack Query holds a call.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BvSDyJABLGit75HAjpnsqm
…fter a thrown error

Review fixes for the retry wait of useSwitchMutation$:

- A `mutationFn` that threw synchronously escaped the hook's wait, and
  with TanStack Query's `retryDelay` of 0 every retry ran at once. The
  source now runs inside `defer`, so a thrown error waits like any other.
- TanStack Query keeps the `retry` of the render that started a call,
  while each attempt runs the latest render's `mutationFn`. When `retry`
  changed during a call, the hook and TanStack Query disagreed: from
  `true` to `false`, the call retried without a delay and never stopped.
  Both now read the latest `retry` and `retryDelay` from one live ref,
  through one `willRetry` that also skips the wait for a source that
  fails with SwitchMutationCancelError.
- `MutationCache.find` takes no type arguments, `defaultRetryDelay` is
  no longer exported, and the docs page lists the three differences
  from TanStack Query.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BvSDyJABLGit75HAjpnsqm
…ryDelay

- `defaultRetryDelay` uses `exponentialBackoffDelay` and `getDelay` from
  `retryBackoff`, as useSubscribeEffect did, instead of a second copy of
  the formula.
- A test checks that a `retryDelay` changed during a call applies from
  the call's next failure on, as the docs page says.
- The test of the client's default `retry` goes: the delay tests already
  build their client with it.
- The docs page says that `retryDelay` must not throw.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BvSDyJABLGit75HAjpnsqm
@mbret
mbret marked this pull request as ready for review November 10, 2026 21:20
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-10T21:23:49.482593Z 6a5c301 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6a5c30152d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/lib/queries/useSwitchMutation$.ts Resolved
@mbret
mbret merged commit ec7dfe8 into main Nov 10, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

useSwitchMutation$: a call cancelled during a retry wait settles only when the wait ends

2 participants